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JUSTIFICATION 

At present* creation of graphic structures for use with the 
Multics Graphic System must be performed by coJing PL/I proce- 
juras which create* edit* and display these structures on an in- 
dividual basis. The program must be re-edited and recompiled to 
alter the structure created. This is especially teuious while 
picture descriptions are still in the debugging stage. It is un- 
reasonable to expect users of the graphic system to code special- 
ized routines to create graphic structures every time a new 
structure is desired, 

PRECEDENTS 

Users of the Version i Graphic System had available to them 
an Author-Maintained program, pix_adit, which functioned as an 
interactive picture editor. With it* users could enter picture 
descriptions, view the results immediately* and perforn. limited 
alterations of their pictures. As pix_edit was not aesigned to 
be a generalized editor, it lacked all but the most rudimentary 
means of altering picture elements (i.e. retyping the entire sub- 
construct.) Users found that it was usually easier to use a text 
editor to place the description into a file* call pix_edit to 
parse and display the construct, and re-enter the editor to make 
alterations. The author of pix_edit (Ken Pogran) later proposed 
a graphic editor tfitn extended features in an RFC. The extended 
editor was never imolemented, 

PROPOSAL 

The attached documentation describes a graphic editor very 
much I ike that proposed in the RFC mentioned. Because of im- 
oroved structure editing capabilities in the Version ? 
graphic_manipu I ator_» it incorporates several new features which 
were not possible to perform using the Version 1 gsm_ package. 
The functionality provided by this interactive tool would be in- 
valuable to both the casual user of graphics and to the implemen- 
tor of extensive graphics applications. 

Comments and sugjestions nay be mailed to Tavares . !iu I t ics on 
System 1 (Phoenix^. 
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MAIDS' graph ic_edi tor, ge 

The graohic_edi tor is an interactive tool which may be used 
to create and eait graphic structures. It is caoable of storing 
these structures into, and retrieving them from, permanent graph- 
ic segments (PGS*s). 



ilsaae. 



graohic_edi tor [segjj tseg2l 



[ segn ] 



1) s?gl (ootional) is a pathname specifying a segment to be 
read, into the graphic editor. This segment m?y contain 
a list of editor commands or assignments, in the same 
format as they might have been typed into the editor 
interactively. The segments will be jnteroreted by the 
editor in the order soecified. 



If any errors occur while reading any segment specified on 
the command line, processing of that file will cease. 



When graohic_editor is ready to 
user's terminal, it replies with 
begin to issue requests. 



receive input from the 
'Edit.". The user may then 



Requests fall into two categories? commands and assign- 
ments. In general, commands may be terminated with either a 
semicolon ("'") or a newline. Assignments (due to their ability 
to be quite lengthy) may be terminatea only with a semicolon. 
Sometimes one of more of the arguments of a command may be an 
assignment. In these cases, only the semicolon is accepted as a 
terminator. 



Comments which are enclosed by 
spersed with any input lines. 



■■/* 



*/' 



may 



be 



i n t er> - 



Symbol s 

Symbols in the graph ic_edi tor are alphanumeric representa- 
tions of node values. A node number is a "receipt" which the 
graphic system returns whenever it is asked to create some graph- 
ic element. (For a more complete description of rode values, 
refer to Section l of the Graphics Users* Supplement.) Symbols 
have a value wnich consists of exactly one such njde value. 

Symbols may be divided into three classes! the system sym- 
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bo I i which is predefined and represents a primitive operation or 
element; the user symbol* which is defined by the user at som« 
time with ar, ass iqnment % and tne macro* which is defined by the 
user, but takes "arguments", and has no permanent value of its 
own. 

System symbols huve no oermanent value. They take one or 
more arguments, either implied or explicit. The use of a system 
symbol represents a reauast that a new element be created. The 
node value returned from that creation is then used in any subse- 
quent operation of that particular expression. 

Fxairples of system symbol expressions are: 

vector 12 lk a vector of length <12, I'm 0) 

"4xolotl" uc a text string containing the string 
"Axolotl", aligned by the upper center 
edge • 

array (a,o,c) an array containing the nodes represent- 
ed by user symbols a, b, ana c. (See 
Tuo I es, bel ow • ) 

I in dotted A made element for dotted lines. 

A list of system symbols and descriptions of their use may 
be found at the end of the document. 

User symbols may be uo to 32 characters in length, and may 
consist of any combination of upper-case and lower-case alphabet- 
ics, numerals, and the underscore ("_")» provided that the first 
character is non-numeric. System symbols and commands are con- 
sidered "reserved words", and may not also be used as user sym- 
ools. Qttemots to define commands as symbols will result in 
ill-formed execution of those commands. 

Fxamoles of user symbols are! 

foo 

Fr on t_corch 

bolt_2 3w9 

User symbols are stored in the graphic symbol table of the work- 
ing graphic segment (WGS) . They are transferred to and from 
PGS's whenever the "save", "use", "put", and "get" system com- 
mands are used. (For a mare complete explanation of graphic sym- 
bols, see Section 1 of the Graphics Users* Supplement.) 
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Macros are user symbols which take arguments like system 
symbols. Whenever a macro expression is evaluated* the arguments 
supolied are substituted for tha dummy arguments with which the 
macro was definea. Macros must be defined by macro assignments. 
For exarcpl e* 

macro box x y = vec x , vec y, vec -x , vec Q -y* 

defines a macro named "box" with dummy arguments "x" and "y". 
The reference! 

box 10 33 

represents a rectangle 1Q units in x and 30 urits in y, and is 
exactly equivalent to the expression? 

vec 10 0, vec 30, vec -lD Q, vec -30 

Macro names are stored in the graphic symbol table of the WGS, 
and may be transferred to an 1 from PGS * s with *he "saue'% "use", 
"put", and "get" commands. 



Tuples 

A tuple is simply a group of one or more values* Every com- 
plete symbol (i.e. a user symbol* or a macro or system symbol 
with its arguments) is a tuole in itself (a one-tuple). A tuple 
of more than one element may be expressed as its elements separa- 
ted by commas, e.g.: 



a, b, b, vec 13 k- 3* intensity 1, xxx 



This is a tuple of 6 elements. 

"• tuole which has more than one element reoresents more thin 
one graphic entity. Therefore, it cannot have one node value. 
To convert a tuole to a single graphic entity, two system symbols 
are available? array, and list. These two "functions" gather the 
elements of the tuole into a graphic array, or a graphic list 
(respectively). (^or a more complete explanation of graphic ar- 
rays and lists, see Section i of the Graphics Users* Supplement.) 
The creation of this array or list produces a node value, which 
may be assigned to a user symbol, or may be usei without assign- 
ment in some larger expression. For example: 

one_array = r*rray (a, b, c, d, b) ' 
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is an assignment which creates a graphic array with the elements 
(a, b, c, d, and bl , and assigns to "one_array" the value of this 
I ist. 



assignments 

An assignment is an ooeration which extracts the value of 
one tuple and assigns it to another tuple. The assignment opera- 
tor is the infix . •' = " sign. 

The simple assignment: 

f oo = bar ? 

specifies that the the value of "foo" is to become the symbol 
"bar". An important point to Keep in mind is that this does rat 
mean that "foo" art "oar" both refer to the identical piece of 
graDhic structure. father, "foo" contains "bar", and (of course) 
indirectly also contains the entire structure contained by "bar". 
(It is possible to assign the v alu e of a symbol to another sym- 
bol* rather than assigning one symbol to another? this operation 
will be discussed in the section describing qualified expres- 
sions.) If "foo" is undefined at the time of assignment, it will 
be created. If it ha-J a previous value* that value will be re- 
placed. Any other graphic structures which referenced "foo" will 
still refer to it, but Hill now contain (indirectly) its new 
va I ue. 

In general, only tuoles of like dimensionality (i.e. having 
the same number of elements) may be assigned to each other. Ft* 
exampl es 

3, b* c = d , e, f : 
x = arrav (p, q, r ) ', 

are both valid assignments. However, 

one, two = three, four, five? 

is not a valid assignment. 

Two exceptions exist to this rule: First, if the object to 
the right of the assignment operator is a one-tuple* it may al- 
ways bP "promoted" into the dimensional ty of the object to the 
left of +he assignment operator. For example: 

a , b* c = ' d ! " 
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is -squi va I ent to 

a = fl! b = dJ c = d! 

The second exception is that if the object to the left of the 

assignment operator is a one-tuDle» and the object to the right 

of the assignment ooerator is not a one-tuple* then the "array" 
operator is assumed. For instance, the assignments: 

a = b , c» d ? 

a = array ( b» \.c . d) ? 

are equivalent. Note that the promotion facility and the impli- 
cit-array ooerator can newer be used simultaneously. This fea- 
ture disallows statements such ->sJ 

one» two = three* four, five? 

which more Drobably represents a user error than a useful state- 
ment. 



Assignments also have values. The value of an assignment is 
the value of the tuple into which tne assignment is done. For 
example, the value of 

too = bar? 

is the new value of "foo". This feature allows nested assign- 
ments* as in the following example: 

oic = some_setpos, (line = vector lOO 1 ? 

This is eauivalert to: 

I ine = vector 100 » 

pic = sonie_se tpos, line? 

Note the us? of the parentheses for precedence definition. The 
oarentheses in the expression ars necessary since tuple formation 
is a "stronger" operation than assignment. If the exDression hal 
been written as! 

pic = some_setpos» line = vector i00? 

it would have been oerformed as the operations: 

some_setnos» line = vector i00? /* a promotion */ 

oic - some_s^t po 5» line? /* an implicit array */ 
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Quai liifta r. xor« i^ i onb 

Tt is possible to refer to any element (or tuple of ele- 
ments) of a symbol which represents an array or list by the use 
of qualified expression. The simDlest qualified expression con- 
sists of a symbol, followed by a period. This represents "the 
value of". In our first example, 

foo = bar* 

we assigned "bar" as the value of "foo". The relationship of 
"foo" to "bar" was a superior/inferior, or father/son relation- 
ship. If, instead, we say 

f oa = bar . ? 

we are assigning the y.aiue of "bar" to "foo". This makes both 
"foo" and "bar" refer to the identical piece of graphic struc- 
ture. The symbols now have a "brother" relationship. 

Successive trailing oeriods denote further levels of evalua- 
tion. Assume the following assignments?. 

box = vec 10, vec 10, vec -10» vec -10! 

a - b = c : <i = box? 

The following relations hold on these symbols! (Read '*£" as "is 
eauivalert to") 

a. = b 

a . . = b . £ c 

a... 5 b«. £ c. £ d 

e . , .. = b .. . £ c. . = d» = box 

The assignment 

a • • • = nu I I .- 

actually assigns "null" to "d". 

Additional types of qualified exoressions make it possible 
to refer to elements of lists. The element desired is denoted by 
an integer following the appropriate levels of qualification. 
For examp I e, 

box. ? 
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is the second element of "box" (vector C iO). Tuples of contigu- 
ous elements may be specified by using a range expression, which 
consists of two integers (represent ing the first ^nd last element 
desired) separated by a colon (":"). For example, 



bottom! ess_box = array ibox.Zik) ' 

will create a symbol which contains an array made up of ail 
ments of "box" except the first. 



e I e- 



The star ("*") has 



, e iia , s , ,,., » a special meaning in a qualified expres- 
sion. If used by itself* e.g. "box.*"*, it refers to a tuple made 
up of all the element of "box". It may also be used as the last 
part of a range expression, e.g. "box.?:*", which refers to a 
tuple made up of all the elements of "box" from the secord to the 
last. The assignment 

hot torn! ess_box = array (box.?:*) 

is equivalent to the example above. Note that if a star occurrs 
in a qua! if ied expression, it must be the ±asji character. It may 
neither be followed by the second component of a range expression 
(e.g. "box.*:3") nor by further levels of qualification (e.g. 
"box.*.l"> . 

because a user may not always know exactly how many levels 
of symbol indirection exist between the symbol name he is working 
with and the arrays or lists with which he desires to work, any 
reference to an element lor range of elements) of a list found in 
a qualified exoression will cause the evaluator to skip any num- 
ber of levels of symbol indirection. Using one of our previous 
examples to elucidate, this means that 



a . I £ a 



box. 1 



This frees the user of typing in I ong, and possibly inaccurate, 
strings of periods? but allows the user w*o wants to maintain 
fine control of his indirect symbol structuring to do precisely 

that . 



Certain qualified exoressioas may \nave different 
the left side of an assignment than they do on the 
This is particularly important to note when using nes 
ments. In particular, qualified expressions which ew 
element of an array or list, or to a tuple of such el 
different meanings in these two contexts. If such a 
occurs on the right side of an assignment, its value 
references to tht- values of the elements which make 
A previous exiruplo ("bot toml ess._box") showed how thi 
interpreted. Or the left side of the assignment, 



meanings on 
right side, 
ted assign- 
aluate to an 
ements, have 
n expression 
consists of 
up the list, 
s usage is 
however, the 
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exnression denotes element ren I acement • Eor instancei assume the 
following assignments: 

box = veo 10, vec 10» vec -1G» vec -1L? 
e I e m = b o x • 3 ' 
box. 3 = shift -id 

The first assignment defines "box". The second assignment causes 
"elem" to refer to the s_a.me piec e of graphic structure which is 
the third element of box. The third assignment changes the "top 
of the oox" from a visible vector to an invisible shift fcy rede- 
fining +he third element of "box" to be a shift of equal magni- 
tude. This does (13.1 change the value of "elem". Tr simply 
breaks the association between the list "box" and the construct 
which was its third element. If the actual changing of that con- 
struct were desired* the third assignment of the above example 
could be replaced with 

box. 3. = shi ft -10 ; 

This assignment would in fact change the value of elem. & 
side-effect of this pfooerty is that the expressions "symbol, n" 
and "symbol, n." are equivalent on the right side of an assign- 
ment* but a^e not equivalent on the left side. 



Node Constants 

It is possible for node values to exist in the WOS without 
being assigned to any symbol. For instance* a user program could 
be called from inside the editor to construct a Dart icul ar 1 y in- 
tricate "canned" graphic structure which may be inefficient or 
difficult to construct by hand. The program could print the num- 
ber of the top-level node in the structure, so that the user 
could "pick it up" by assigning a name to it. The number of this 
node may be tvoeci in, preceded by the character "#". This is j 
"node constant". 

For examole: if *he node constant "#123^5" appears as such 
an outout, ^nd it is dished to assign to this node the name 
"orphan", the assignment: 

orphan = #l?3 l o*' 

may be used. 

Octal node values may he exnressed directly as node con- 
stants without user conversion by immediately following the "If" 
with the lowercase letter "o", e.-i. ,, #ol<*<+" is equivalent to 

"#100". 
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Although nod? constants and qualified expressions based on 
node constants are allowed on the left-hand side of assignment 
statements* their use is strongly discouraged. 



Commands ■ 

Following is a list of editor commands. Arguments enclosed 
in angle backets ("< ... >") denote necessary arguments. Argu- 
ments enclosed in square brackets ("[ ... 1"). denote optional 
arguments. Each command whose argument is signified by <exprn> 
will accept single elements* tuples* assignments, or any combina- 
tion of these as its argument. For example? 

display pic = array Chouse, street* oarked_cars) ? 

serves the dual puroose of defining "pic" and disolaying it. 



>--- > display <exprn> 

di <Q*.crn> 
causes the screen to be erased and the graphic structure speci- 
fied to be displayed. If the argument is a tuple* no erase is 
performed between eacn element of the tuple. 



> > list [optionsi 

Is [options] 
will list selectad symbol tables. Any number of options may be 
specified. The following options are allowed: 

-commands -com list the editor commands and their abbreviations. 

-system -sys list the available system symbols and their ab- 
breviat ions. 

-macros *mc list the defined macros. 

-symbols -sym list the user symbols. 

-all -a list all oft he above. 

If no options are given, "-symbols" is assumed. 



> > execute <command_l ine> 

exec <command__l ire> 
causes the <command_ I ine> to be passed to the command processor. 
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> > show <exorn> 

causes an abbrev iated descriotion af the tuple <exprn> to be 
or in ted to the user's terminal. It the value represents a termi- 
nal graphic element, its contents will be printed. If it repre- 
sents a non-terminal element* it will be described and the nuitber 
of its elements oiven. 



> > replay <exprn> 

like show, except that the entire graohic Subtree inferior to the 
chosen node is described in assignment notation, along with nes- 
ted assignments where appropriate. This command allows a user to 
"reolay" a jraohic structure in a form acceptable as inout to the 
graph ic_ed it or. 



>---> remove <svmboll> [symbol?] ... IsymbolnJ 
causes those elements named to be removed from the table of known 
user symbols. The symbol in the WGS is also deleted, and all 
references to it will be transformed into direct references to 
whatever contents it possessed. 



> > use [pathname! 

causes the oermanent jraohic segment (PGS) soecified by [path- 
name] to be loaded into the WGS. This allows the editor to use a 
previous ly-construc ted set of graphic structures. If [pathname] 
is not supplied, graph ic_edi tor will use the Dathname which was 
last suoplied to a "use" or "save" command. If no such pathname 
exists, an error will occur. If an error occurs during the exe- 
cution of i "use" command, the "last pathname" will be deliber- 
ately forgotten. 



> > save [pathname] 

causes the confer ts of tha WGS to be saved in a PGS specified by 
[pathname]. If [Dathname] is not supplied, graohic_edi tor wilt 
use the Dathname which was last supplied to a "use" or "save" 
command. If no such pathname exists, an error will occur. If an 
error occurs during the execution of a "save" command, the "last 
oathname" will be deliberately forgotten. 



> > get [mode] [(pathname)] <sym> [sym?] ... Isymn] 

gets the structures <symi> ... (symnj from the PGS specified by 
[ (pathname) t . (This notation means that "pathname", if it is 
given, must be within parentheses.) The (mode] argument deter- 
mines what action is taken on attempts to redefine an existing 
name ! 
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-safe leave the old symbol as is and print en error message. 
-force redefine the symbol and all subsidiary symbols. 

-rep I ace_onl y 

-rpo redefine the symbol. If suosidiary symbols are dupli- 
cated in the WGS, use the copies in the WGS. For any 
subsidiary symbols not so duplicated* create null 
(empty) symbols. 

-reo I ace_a I I 

-rpa redefine the symbol. If subsidiary symbols are dupli- 
cated in the WGS, use the copies in the WGS. For any 
subsidiary symbols which do not exist in the WGS, us? 
the ones in the PGS. 

If [mode] is not specified, "-safe" will be assumed. The [model 
and [(pathname) ] arguments, if present, may occur in either 
order, but must precede any symbol names. 



> > put [model [(pathname) 1 <symi> [sym?l ... [symnl 

stores the structures <syml> ... Isymn] into the PGS specified by 
[(pathname)!. the [model argument determines what action is 
taken on attempts to redefine an existing name: 

-safe leave the old symbol js is and print an error message. 

-force redefine th* symbol and all subsidiary symools. 

-rep I ace_onl y 

-rpo redefine the symbol. If subsidiary symbols are dupli- 
cated in the PGS, use the copies in the PGS. For any 
subsidiary symbols not so duplicated, create null 
(emoty ) symbo I s. 

-reol ace_a I ! ■ 

-ro3 redefine the symbol. If subsidiary symbols are duoli- 
cated in the PGS, use the copies in the PGS. For any 
subsidiary symbols which do not exist irs the PGS, use 
the ones in the WGS. 

If [mode] is not specified, "-safe" will be assumed. The permis- 
sible order of the arguments is the same as for "get". 



> > real <pathname> 

causes the file specified by <oathname> to be interpretec as a 

set of editor commands. Any "real" command encounterea in a file 

will switch thrf input source to the specified file. When the 
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commands in the specified file have been exhausted, control will 
return to the user's terminal, or to the original file issuinj 
the "read". Frrors encountered while reading from a segment wiii 
cause control to be immediately returned to the user's terminal. 



> > quit 

is used to exit from the editor. 



> — -> restart 

will re-initialize the editor, the working graphic segment, and 
all associated symbol tables. Anv remaining command line, as 
well as any file "reads" pending, will be flushed without execu- 
tion. The state of the editor after a "restart" is the same as 
the state of the editor when it is first invoked. 



> > help 

■> 

directs the user +o relevant dccumantat ion. 



> > macro <name> targiJ ... [argn.1 = <exprn> 

macro show <namei> *.. [namenl 

macro replay <namel> . .. [namenl 
The first form defines a macro with name <nan:e>, and arguments 
[argil .*• [argnj. The other forms do for macros what "show" and 
"replay" do for symbols. 



>---> input <symbol> t device_namel 

requests that a "what" input be requested from device 
[device_name 1. The inout will be collected, interpreted, made 
into a graphic structure, and assigned to symbol <symbol>. This 
feature is not yet imp I ement ad . 



Defined System Symbols 



Positional Elements 

All positional elements take arguments of the form "x y z". 
If any of these arguments are not supplied, it will be assumed to 
be zero. It is possible to supply no arguments, only "x", 
only "x y" , or all of "x y 7". No other combinations (e.g. 
"x z") are oarsable. 
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setposition (sps) 
setpoint (sot) 



vector (vac) 

sh i r t < s f n 

point (pntl 



Modal f laments 

>- — > intensity tint) 

argument: Integer, Q through 7, or "off* (Q)t "on" (7), or "full 

(71 . 

> > linetyre ( ! inl 

argument: Integer* 1 through 5, iri 

"sol id" (1) 

"dashed" (?) 

"dotted" <3» 

"dash_dotte<1" <<♦) 

"long.dashed" (5) 

> > bl ink (blk) 

arguments mav be any from the following correspondence list: 

"steady" 

"blinking" 1 

> > sensitivity (sns) 

Arguments may be any from the following correspondence lists 

"insensitive" 

"sensitive" 1 



Mapping Elements 

>---> rotation (rot) 

Arguments: "x_rotation y_rotation z_rotation" in floating or in- 
teger degrees. 

>---> seal ing (sc! ) 

Arguments: "x_scale y_scale z_scale" in integer or floating nota- 
tion. 



Miscellaneous Elements 

> > nu I I 

Mo arguments. This element represents the "zero node". It is a 
placeholder, or a graphic no-op. 

> > text "string" toositionj 
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"strina" [position] 
The second form of th<^ text string is implicitly understood. The 
optional argument [position] specifies the string alignment. 
(For a more complete explanation of string alignments, refer to 
Section l of the Graphics Users* Supplement.) Any character miy 
appear within the string. If it is desired for a quote to appear 
as part f t ne string, it may oe doubled, as in f>L/I. 
merit may be either an integer or a string, fron 
correspondence list 5 



The argu- 
the foil owing 



uop»r_| eft 
upoer_cen ter 
uooer_r ight 
left 
center 
right 

lower_lef t 
I ower_center 
I ower_r ight 



ul 

uc 

ur 

I 

c 

r 

I I 

Ic 

Ir 



1 
2 
3 
k 
5 
6 
7 
8 
9 



>---> datablock <element> 

data <element> 
creates a datablock containing the element <element>. This ele- 
ment may be of a form acceptable as a symbol r,ame, or numeric, or 
3 string encloseo in quotes. It may not be a break character 
("•"» "»", etc.) unless enclosed in quotes. Datablocks may be 
used to hold information relevant to the structure, within the 
structure itself. (For a more complete explanation of data- 
blocks, refer to Section i of the Graphics Users* Supplement.) 
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